home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Languguage OS 2
/
Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO
/
gnu
/
elispman.lha
/
elispman
/
elisp-17
(
.txt
)
< prev
next >
Wrap
GNU Info File
|
1993-06-01
|
46KB
|
832 lines
This is Info file elisp, produced by Makeinfo-1.55 from the input file
elisp.texi.
This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for
Emacs Version 19.
Published by the Free Software Foundation, 675 Massachusetts Avenue,
Cambridge, MA 02139 USA
Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.
File: elisp, Node: Accessing Documentation, Next: Keys in Documentation, Prev: Documentation Basics, Up: Documentation
Access to Documentation Strings
===============================
- Function: documentation-property SYMBOL PROPERTY &optional VERBATIM
This function returns the documentation string that is recorded
SYMBOL's property list under property PROPERTY. This uses the
function `get', but does more than that: it also retrieves the
string from the file `emacs/etc/DOC-VERSION' if necessary, and
runs `substitute-command-keys' to substitute the actual (current)
key bindings.
If VERBATIM is non-`nil', that inhibits running
`substitute-command-keys'. (The VERBATIM argument exists only as
of Emacs 19.)
(documentation-property 'command-line-processed
'variable-documentation)
=> "t once command line has been processed"
(symbol-plist 'command-line-processed)
=> (variable-documentation 188902)
- Function: documentation FUNCTION &optional VERBATIM
This function returns the documentation string of FUNCTION. If
the documentation string is stored in the `emacs/etc/DOC-VERSION'
file, this function will access it there.
In addition, `documentation' runs `substitute-command-keys' on the
resulting string, so the value contains the actual (current) key
bindings. (This is not done if VERBATIM is non-`nil'; the
VERBATIM argument exists only as of Emacs 19.)
The function `documentation' signals a `void-function' error
unless FUNCTION has a function definition. However, FUNCTION does
not need to have a documentation string. If there is no
documentation string, `documentation' returns `nil'.
Here is an example of using the two functions, `documentation' and
`documentation-property', to display the documentation strings for
several symbols in a `*Help*' buffer.
(defun describe-symbols (pattern)
"Describe the Emacs Lisp symbols matching PATTERN.
All symbols that have PATTERN in their name are described
in the `*Help*' buffer."
(interactive "sDescribe symbols matching: ")
(let ((describe-func
(function
(lambda (s)
;; Print description of symbol.
(if (fboundp s) ; It is a function.
(princ
(format "%s\t%s\n%s\n\n" s
(if (commandp s)
(let ((keys (where-is-internal s)))
(if keys
(concat
"Keys: "
(mapconcat 'key-description
keys " "))
"Keys: none"))
"Function")
(or (documentation s)
"not documented"))))
(if (boundp s) ; It is a variable.
(princ
(format "%s\t%s\n%s\n\n" s
(if (user-variable-p s)
"Option " "Variable")
(or (documentation-property
s 'variable-documentation)
"not documented")))))))
sym-list)
;; Build a list of symbols that match pattern.
(mapatoms (function
(lambda (sym)
(if (string-match pattern (symbol-name sym))
(setq sym-list (cons sym sym-list))))))
;; Display the data.
(with-output-to-temp-buffer "*Help*"
(mapcar describe-func (sort sym-list 'string<))
(print-help-return-message))))
The `describe-symbols' function works like `apropos', but provides
more information.
(describe-symbols "goal")
---------- Buffer: *Help* ----------
goal-column Option
*Semipermanent goal column for vertical motion, as set by C-x C-n, or nil.
set-goal-column Command: C-x C-n
Set the current horizontal position as a goal for C-n and C-p.
Those commands will move to this position in the line moved to
rather than trying to keep the same horizontal position.
With a non-nil argument, clears out the goal column
so that C-n and C-p resume vertical motion.
The goal column is stored in the variable `goal-column'.
temporary-goal-column Variable
Current goal column for vertical motion.
It is the column where point was
at the start of current run of vertical motion commands.
When the `track-eol' feature is doing its job, the value is 9999.
---------- Buffer: *Help* ----------
- Function: Snarf-documentation FILENAME
This function is used only during Emacs initialization, just before
the runnable Emacs is dumped. It finds the file offsets of the
documentation strings stored in the file FILENAME, and records
them in the in-core function definitions and variable property
lists in place of the actual strings. *Note Building Emacs::.
Emacs finds the file FILENAME in the `emacs/etc' directory. When
the dumped Emacs is later executed, the same file is found in the
directory `data-directory'. Usually FILENAME is `"DOC-VERSION"'.
- Variable: data-directory
This variable holds the name of the directory in which Emacs finds
certain data files that come with Emacs or are built as part of
building Emacs. (In older Emacs versions, this directory was the
same as `exec-directory'.)
File: elisp, Node: Keys in Documentation, Next: Describing Characters, Prev: Accessing Documentation, Up: Documentation
Substituting Key Bindings in Documentation
==========================================
This function makes it possible for you to write a documentation
string that enables a user to display information about the current,
actual key bindings. if you call `documentation' with non-`nil'
VERBATIM, you might later call this function to do the substitution
that you prevented `documentation' from doing.
- Function: substitute-command-keys STRING
This function returns STRING with certain special substrings
replaced by the actual (current) key bindings. This permits the
documentation to be displayed with accurate information about key
bindings. (The key bindings may be changed by the user between
the time Emacs is built and the time that the documentation is
asked for.)
This table lists the forms of the special substrings and what they
are replaced with:
`\[COMMAND]'
is replaced either by a keystroke sequence that will invoke
COMMAND, or by `M-x COMMAND' if COMMAND is not bound to any
key sequence.
`\{MAPVAR}'
is replaced by a summary of the value of MAPVAR, taken as a
keymap. (The summary is made by `describe-bindings'.)
`\<MAPVAR>'
makes this call to `substitute-command-keys' use the value of
MAPVAR as the keymap for future `\[COMMAND]' substrings.
This special string does not produce any replacement text
itself; it only affects the replacements done later.
*Please note:* each `\' must be doubled when written in a string
in Emacs Lisp.
Here are examples of the special substrings:
(substitute-command-keys
"To abort recursive edit, type: \\[abort-recursive-edit]")
=> "To abort recursive edit, type: C-]"
(substitute-command-keys
"The keys that are defined for the minibuffer here are:
\\{minibuffer-local-must-match-map}")
=> "The keys that are defined for the minibuffer here are:
? minibuffer-completion-help
SPC minibuffer-complete-word
TAB minibuffer-complete
LFD minibuffer-complete-and-exit
RET minibuffer-complete-and-exit
C-g abort-recursive-edit
"
(substitute-command-keys
"To abort a recursive edit from the minibuffer, type\
\\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
=> "To abort a recursive edit from the minibuffer, type C-g."
File: elisp, Node: Describing Characters, Next: Help Functions, Prev: Keys in Documentation, Up: Documentation
Describing Characters for Help Messages
=======================================
These functions convert events, key sequences or characters to
textual descriptions. These descriptions are useful for including
arbitrary text characters or key sequences in messages, because they
convert non-printing characters to sequences of printing characters.
The description of a printing character is the character itself.
- Function: key-description SEQUENCE
This function returns a string containing the Emacs standard
notation for the input events in SEQUENCE. The argument SEQUENCE
may be a string, vector or list. *Note Input Events::, for more
information about valid events. See also the examples for
`single-key-description', below.
- Function: single-key-description EVENT
This function returns a string describing EVENT in the standard
Emacs notation for keyboard input. A normal printing character is
represented by itself, but a control character turns into a string
starting with `C-', a meta character turns into a string starting
with `M-', and space, linefeed, etc. are transformed to `SPC',
`LFD', etc. A function key is represented by its name. An event
which is a list is represented by the name of the symbol in the CAR
of the list.
(single-key-description ?\C-x)
=> "C-x"
(key-description "\C-x \M-y \n \t \r \f123")
=> "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
(single-key-description 'C-mouse-1)
=> "C-mouse-1"
- Function: text-char-description CHARACTER
This function returns a string describing CHARACTER in the
standard Emacs notation for characters that appear in text--like
`single-key-description', except that control characters are
represented with a leading caret (which is how control characters
in Emacs buffers are usually displayed).
(text-char-description ?\C-c)
=> "^C"
(text-char-description ?\M-m)
=> "M-m"
(text-char-description ?\C-\M-m)
=> "M-^M"
File: elisp, Node: Help Functions, Prev: Describing Characters, Up: Documentation
Help Functions
==============
Emacs provides a variety of on-line help functions, all accessible to
the user as subcommands of the prefix `C-h'. For more information
about them, see *Note Help: (emacs)Help. Here we describe some
program-level interfaces to the same information.
- Command: apropos REGEXP &optional DO-ALL PREDICATE
This function finds all symbols whose names contain a match for the
regular expression REGEXP, and returns a list of them. It also
displays the symbols in a buffer named `*Help*', each with a
one-line description.
If DO-ALL is non-`nil', then `apropos' also shows key bindings for
the functions that are found.
If PREDICATE is non-`nil', it should be a function to be called on
each symbol that has matched REGEXP. Only symbols for which
PREDICATE returns a non-`nil' value are listed or displayed.
In the first of the following examples, `apropos' finds all the
symbols with names containing `exec'. In the second example, it
finds and returns only those symbols that are also commands. (We
don't show the output that results in the `*Help*' buffer.)
(apropos "exec")
=> (Buffer-menu-execute command-execute exec-directory
exec-path execute-extended-command execute-kbd-macro
executing-kbd-macro executing-macro)
(apropos "exec" nil 'commandp)
=> (Buffer-menu-execute execute-extended-command)
The command `C-h a' (`command-apropos') calls `apropos', but
specifies a PREDICATE to restrict the output to symbols that are
commands. The call to `apropos' looks like this:
(apropos string t 'commandp)
- Command: super-apropos REGEXP &optional DO-ALL
This function differs from `apropos' in that it searches
documentation strings as well as symbol names for matches for
REGEXP. By default, it searches only the documentation strings,
and only those of functions and variables that are included in
Emacs when it is dumped. If DO-ALL is non-`nil', it scans the
names and documentation strings of all functions and variables.
- Command: help-command
This command is not a function, but rather a symbol which is
equivalent to the keymap called `help-map'. It is defined in
`help.el' as follows:
(define-key global-map "\C-h" 'help-command)
(fset 'help-command help-map)
- Variable: help-map
The value of this variable is a local keymap for characters
following the Help key, `C-h'.
- Function: print-help-return-message &optional FUNCTION
This function builds a string which is a message explaining how to
restore the previous state of the windows after a help command.
After building the message, it applies FUNCTION to it if FUNCTION
is non-`nil'. Otherwise it calls `message' to display it in the
echo area.
This function expects to be called inside a
`with-output-to-temp-buffer' special form, and expects
`standard-output' to have the value bound by that special form.
For an example of its use, see the example in the section
describing the `documentation' function (*note Accessing
Documentation::.).
The constructed message will have one of the forms shown below.
---------- Echo Area ----------
Type C-x 1 to remove help window.
---------- Echo Area ----------
---------- Echo Area ----------
Type C-x 4 b RET to restore old contents of help window.
---------- Echo Area ----------
- Variable: help-char
The value of this variable is the character that Emacs recognizes
as meaning Help. When Emacs reads this character (which is
usually 8, the value of `C-h'), Emacs evaluates `(eval
help-form)', and displays the result if it is a string. If
`help-form''s value is `nil', this character is read normally.
- Variable: help-form
The value of this variable is a form to execute when the character
`help-char' is read. If the form returns a string, that string is
displayed. If `help-form' is `nil', then the help character is
not recognized.
Entry to the minibuffer binds this variable to the value of
`minibuffer-help-form'.
The following two functions are found in the library `helper'. They
are for modes that want to provide help without relinquishing control,
such as the "electric" modes. You must load that library with
`(require 'helper)' in order to use them. Their names begin with
`Helper' to distinguish them from the ordinary help functions.
- Command: Helper-describe-bindings
This command pops up a window displaying a help buffer containing a
listing of all of the key bindings from both the local and global
keymaps. It works by calling `describe-bindings'.
- Command: Helper-help
This command provides help for the current mode. It prompts the
user in the minibuffer with the message `Help (Type ? for further
options)', and then provides assistance in finding out what the key
bindings are, and what the mode is intended for. It returns `nil'.
This can be customized by changing the map `Helper-help-map'.
File: elisp, Node: Files, Next: Backups and Auto-Saving, Prev: Documentation, Up: Top
Files
*****
In Emacs, you can find, create, view, save, and otherwise work with
files and file directories. This chapter describes most of the
file-related functions of Emacs Lisp, but a few others are described in
*Note Buffers::, and those related to backups and auto-saving are
described in *Note Backups and Auto-Saving::.
* Menu:
* Visiting Files:: Reading files into Emacs buffers for editing.
* Saving Buffers:: Writing changed buffers back into files.
* Reading from Files:: Reading files into buffers without visiting.
* Writing to Files:: Writing new files from parts of buffers.
* File Locks:: Locking and unlocking files, to prevent
simultaneous editing by two people.
* Information about Files:: Testing existence, accessibility, size of files.
* Contents of Directories:: Getting a list of the files in a directory.
* Create/Delete Dirs:: Creating and Deleting Directories.
* Changing File Attributes:: Renaming files, changing protection, etc.
* File Names:: Decomposing and expanding file names.
* Magic File Names:: Defining "magic" special handling
for certain file names.
File: elisp, Node: Visiting Files, Next: Saving Buffers, Up: Files
Visiting Files
==============
Visiting a file means reading a file into a buffer. Once this is
done, we say that the buffer is "visiting" that file, and call the file
"the visited file" of the buffer.
A file and a buffer are two different things. A file is information
recorded permanently in the computer (unless you delete it). A buffer,
on the other hand, is information inside of Emacs that will vanish at
the end of the editing session (or when you kill the buffer). Usually,
a buffer contains information that you have copied from a file; then we
say the buffer is visiting that file. The copy in the buffer is what
you modify with editing commands. Such changes to the buffer do not
change the file; therefore, to make the changes permanent, you must
"save" the buffer, which means copying the altered buffer contents back
into the file.
In spite of the distinction between files and buffers, people often
refer to a file when they mean a buffer and vice-versa. Indeed, we say,
"I am editing a file," rather than, "I am editing a buffer which I will
soon save as a file of the same name." Humans do not usually need to
make the distinction explicit. When dealing with a computer program,
however, it is good to keep the distinction in mind.
* Menu:
* Visiting Functions:: The usual interface functions for visiting.
* Subroutines of Visiting:: Lower-level subroutines that they use.
File: elisp, Node: Visiting Functions, Next: Subroutines of Visiting, Up: Visiting Files
Functions for Visiting Files
----------------------------
This section describes the functions normally used to visit files.
For historical reasons, these functions have names starting with
`find-' rather than `visit-'. *Note Buffer File Name::, for functions
and variables that access the visited file name of a buffer or that
find an existing buffer by its visited file name.
- Command: find-file FILENAME
This function reads the file FILENAME into a buffer and displays
that buffer in the selected window so that the user can edit it.
The body of the `find-file' function is very simple and looks like
this:
(switch-to-buffer (find-file-noselect filename))
(See `switch-to-buffer' in *Note Displaying Buffers::.)
When `find-file' is called interactively, it prompts for FILENAME
in the minibuffer.
- Function: find-file-noselect FILENAME
This function is the guts of all the file-visiting functions. It
reads a file into a buffer and returns the buffer. You may then
make the buffer current or display it in a window if you wish, but
this function does not do so.
If no buffer is currently visiting FILENAME, then one is created
and the file is visited. If FILENAME does not exist, the buffer
is left empty, and `find-file-noselect' displays the message `New
file' in the echo area.
If a buffer is already visiting FILENAME, then the
`find-file-noselect' function uses that buffer rather than creating
a new one. However, it does verify that the file has not changed
since it was last visited or saved in that buffer. If the file
has changed, then this function asks the user whether to reread
the changed file. If the user says `yes', any changes previously
made in the buffer are lost.
The `find-file-noselect' function calls `after-find-file' after
the file is read in (*note Subroutines of Visiting::.). The
`after-find-file' function sets the buffer major mode, parses local
variables, warns the user if there exists an auto-save file more
recent than the file just visited, and finishes by running the
functions in `find-file-hooks'.
The `find-file-noselect' function returns the buffer that is
visiting the file FILENAME.
(find-file-noselect "/etc/fstab")
=> #<buffer fstab>
- Command: find-alternate-file FILENAME
This function reads the file FILENAME into a buffer and selects
it, killing the buffer current at the time the command is run. It
is useful if you have visited the wrong file by mistake, so that
you can get rid of the buffer that you did not want to create, at
the same time as you visit the file you intended.
When this function is called interactively, it prompts for
FILENAME.
- Command: find-file-other-window FILENAME
This function visits the file FILENAME and displays its buffer in
a window other than the selected window. It may use another
existing window or split a window; see *Note Displaying Buffers::.
When this function is called interactively, it prompts for
FILENAME.
- Command: find-file-read-only FILENAME
This function visits the file named FILENAME and selects its
buffer, just like `find-file', but it marks the buffer as
read-only. *Note Read Only Buffers::, for related functions and
variables.
When this function is called interactively, it prompts for
FILENAME.
- Command: view-file FILENAME
This function views FILENAME in View mode, returning to the
previous buffer when done. View mode is a mode that allows you to
skim rapidly through the file but does not let you modify it.
After loading the file, `view-file' runs the normal hook
`view-hook' using `run-hooks'. *Note Hooks::.
When this function is called interactively, it prompts for
FILENAME.
- Variable: find-file-hooks
The value of this variable is a list of functions to be called
after a file is visited. The file's local-variables specification
(if any) will have been processed before the hooks are run. The
buffer visiting the file is current when the hook functions are
run.
This variable could be a normal hook, but we think that renaming it
would not be advisable.
- Variable: find-file-not-found-hooks
The value of this variable is a list of functions to be called when
`find-file' or `find-file-noselect' is passed a nonexistent
FILENAME. These functions are called as soon as the error is
detected. `buffer-file-name' is already set up. The functions are
called in the order given, until one of them returns non-`nil'.
This is not a normal hook because the values of the functions are
used and they may not all be run.
File: elisp, Node: Subroutines of Visiting, Prev: Visiting Functions, Up: Visiting Files
Subroutines of Visiting
-----------------------
The `find-file-noselect' function uses the `create-file-buffer' and
`after-find-file' functions as subroutines. Sometimes it is useful to
call them directly.
- Function: create-file-buffer FILENAME
This function creates a suitably named buffer for visiting
FILENAME, and returns it. The string FILENAME (sans directory) is
used unchanged if that name is free; otherwise, a string such as
`<2>' is appended to get an unused name. See also *Note Creating
Buffers::.
*Please note:* `create-file-buffer' does *not* associate the new
buffer with a file and does not make it the current buffer.
(create-file-buffer "foo")
=> #<buffer foo>
(create-file-buffer "foo")
=> #<buffer foo<2>>
(create-file-buffer "foo")
=> #<buffer foo<3>>
This function is used by `find-file-noselect'. It uses
`generate-new-buffer' (*note Creating Buffers::.).
- Function: after-find-file &optional ERROR WARN
This function is called by `find-file-noselect' and by the default
revert function (*note Reverting::.). It sets the buffer major
mode, and parses local variables (*note Auto Major Mode::.).
If there was an error in opening the file, the calling function
should pass ERROR a non-`nil' value. In that case,
`after-find-file' issues a warning: `(New File)'. Note that, for
serious errors, you would not even call `after-find-file'. Only
"file not found" errors get here with a non-`nil' ERROR.
If WARN is non-`nil', then this function issues a warning if an
auto-save file exists and is more recent than the visited file.
The last thing `after-find-file' does is call all the functions in
`find-file-hooks'.
File: elisp, Node: Saving Buffers, Next: Reading from Files, Prev: Visiting Files, Up: Files
Saving Buffers
==============
When you edit a file in Emacs, you are actually working on a buffer
that is visiting that file--that is, the contents of the file are
copied into the buffer and the copy is what you edit. Changes to the
buffer do not change the file until you "save" the buffer, which means
copying the contents of the buffer into the file.
- Command: save-buffer &optional BACKUP-OPTION
This function saves the contents of the current buffer in its
visited file if the buffer has been modified since it was last
visited or saved. Otherwise it does nothing.
`save-buffer' is responsible for making backup files. Normally,
BACKUP-OPTION is `nil', and `save-buffer' makes a backup file only
if this is the first save or if the buffer was previously
modified. Other values for BACKUP-OPTION request the making of
backup files in other circumstances:
* With an argument of 4 or 64, reflecting 1 or 3 `C-u''s, the
`save-buffer' function marks this version of the file to be
backed up when the buffer is next saved.
* With an argument of 16 or 64, reflecting 2 or 3 `C-u''s, the
`save-buffer' function unconditionally backs up the previous
version of the file before saving it.
- Command: save-some-buffers &optional SAVE-SILENTLY-P EXITING
This command saves some modified file-visiting buffers. Normally
it asks the user about each buffer. But if SAVE-SILENTLY-P is
non-`nil', it saves all the file-visiting buffers without querying
the user.
The optional EXITING argument, if non-`nil', requests this
function to offer also to save certain other buffers that are not
visiting files. These are buffers that have a non-`nil' local
value of `buffer-offer-save'. (A user who says yes to saving one
of these is asked to specify a file name to use.) The
`save-buffers-kill-emacs' function passes a non-`nil' value for
this argument.
- Variable: buffer-offer-save
When this variable is non-`nil' in a buffer, Emacs offers to save
the buffer on exit even if the buffer is not visiting a file. The
variable is automatically local in all buffers. Normally, Mail
mode (used for editing outgoing mail) sets this to `t'.
- Command: write-file FILENAME
This function writes the current buffer into file FILENAME, makes
the buffer visit that file, and marks it not modified. The buffer
is renamed to correspond to FILENAME unless that name is already
in use.
- Variable: write-file-hooks
The value of this variable is a list of functions to be called
before writing out a buffer to its visited file. If one of them
returns non-`nil', the file is considered already written and the
rest of the functions are not called, nor is the usual code for
writing the file executed.
If a function in `write-file-hooks' returns non-`nil', it is
responsible for making a backup file (if that is appropriate). To
do so, execute the following code:
(or buffer-backed-up (backup-buffer))
You might wish to save the file modes value returned by
`backup-buffer' and use that to set the mode bits of the file that
you write. This is what `basic-save-buffer' does when it writes a
file in the usual way.
Here is an example showing how to add an element to
`write-file-hooks' but avoid adding it twice:
(or (memq 'my-write-file-hook write-file-hooks)
(setq write-file-hooks
(cons
'my-write-file-hook write-file-hooks)))
- Variable: local-write-file-hooks
This works just like `write-file-hooks', but it is intended to be
made local to particular buffers. It's not a good idea to make
`write-file-hooks' local to a buffer--use this variable instead.
The variable is marked as a permanent local, so that changing the
major mode does not alter a buffer-local value. This is
convenient for packages that read "file" contents in special ways,
and set up hooks to save the data in a corresponding way.
- Variable: write-contents-hooks
This works just like `write-file-hooks', but it is intended to be
used for hooks that pertain to the contents of the file, as
opposed to hooks that pertain to where the file came from.
- Variable: after-save-hook
This normal hook runs after a buffer has been saved in its visited
file.
- Variable: file-precious-flag
If this variable is non-`nil', then `save-buffer' protects against
I/O errors while saving by writing the new file to a temporary
name instead of the name it is supposed to have, and then renaming
it to the intended name after it is clear there are no errors.
This procedure prevents problems such as a lack of disk space from
resulting in an invalid file.
(This feature worked differently in older Emacs versions.)
Some modes set this non-`nil' locally in particular buffers.
- User Option: require-final-newline
This variable determines whether files may be written out that do
*not* end with a newline. If the value of the variable is `t',
then Emacs silently puts a newline at the end of the file whenever
the buffer being saved does not already end in one. If the value
of the variable is non-`nil', but not `t', then Emacs asks the
user whether to add a newline each time the case arises.
If the value of the variable is `nil', then Emacs doesn't add
newlines at all. `nil' is the default value, but a few major modes
set it to `t' in particular buffers.
File: elisp, Node: Reading from Files, Next: Writing to Files, Prev: Saving Buffers, Up: Files
Reading from Files
==================
You can copy a file from the disk and insert it into a buffer using
the `insert-file-contents' function. Don't use the user-level command
`insert-file' in a Lisp program, as that sets the mark.
- Function: insert-file-contents FILENAME &optional VISIT
This function inserts the contents of file FILENAME into the
current buffer after point. It returns a list of the absolute file
name and the length of the data inserted. An error is signaled if
FILENAME is not the name of a file that can be read.
If VISIT is non-`nil', it also marks the buffer as unmodified and
sets up various fields in the buffer so that it is visiting the
file FILENAME: these include the buffer's visited file name and
its last save file modtime. This feature is used by
`find-file-noselect' and you should probably not use it yourself.
If you want to pass a file name to another process so that another
program can read the file, see the function `file-local-copy' in *Note
Magic File Names::.
File: elisp, Node: Writing to Files, Next: File Locks, Prev: Reading from Files, Up: Files
Writing to Files
================
You can write the contents of a buffer, or part of a buffer, directly
to a file on disk using the `append-to-file' and `write-region'
functions. Don't use these functions to write to files that are being
visited; that could cause confusion in the mechanisms for visiting.
- Command: append-to-file START END FILENAME
This function appends the contents of the region delimited by
START and END in the current buffer to the end of file FILENAME.
If that file does not exist, it is created. This function returns
`nil'.
An error is signaled if FILENAME specifies a nonwritable file, or
a nonexistent file in a directory where files cannot be created.
- Command: write-region START END FILENAME &optional APPEND VISIT
This function writes the region (of the current buffer) delimited
by START and END into the file specified by FILENAME.
If START is a string, then `write-region' writes or appends that
string, rather than text from the buffer.
If APPEND is non-`nil', then the region is appended to the
existing file contents (if any).
If VISIT is `t', then Emacs establishes an association between the
buffer and the file: the buffer is then visiting that file. It
also sets the last file modification time for the current buffer to
FILENAME's modtime, and marks the buffer as not modified. This
feature is used by `write-file' and you should probably not use it
yourself.
If VISIT is a string, it specifies the file name to visit. This
way, you can write the data to one file (FILENAME) while recording
the buffer as visiting another file (VISIT). The argument VISIT
is used in the echo area message and also for file locking; VISIT
is stored in `buffer-file-name'. This feature is used to
implement `file-precious-flag'; don't use it yourself unless you
really know what you're doing.
Normally, `write-region' displays a message `Wrote file FILENAME'
in the echo area. If VISIT is neither `t' nor `nil' nor a string,
then this message is inhibited. This feature is useful for
programs that use files for internal purposes, files which the
user does not need to know about.
File: elisp, Node: File Locks, Next: Information about Files, Prev: Writing to Files, Up: Files
File Locks
==========
When two users edit the same file at the same time, they are likely
to interfere with each other. Emacs tries to prevent this situation
from arising by recording a "file lock" when a file is being modified.
Emacs can then detect the first attempt to modify a buffer visiting a
file that is locked by another Emacs job, and ask the user what to do.
File locks do not work properly when multiple machines can share
file systems, such as with NFS. Perhaps a better file locking system
will be implemented in the future. When file locks do not work, it is
possible for two users to make changes simultaneously, but Emacs can
still warn the user who saves second. Also, the detection of
modification of a buffer visiting a file changed on disk catches some
cases of simultaneous editing; see *Note Modification Time::.
- Function: file-locked-p FILENAME
This function returns `nil' if the file FILENAME is not locked by
this Emacs process. It returns `t' if it is locked by this Emacs,
and it returns the name of the user who has locked it if it is
locked by someone else.
(file-locked-p "foo")
=> nil
- Function: lock-buffer &optional FILENAME
This function locks the file FILENAME, if the current buffer is
modified. The argument FILENAME defaults to the current buffer's
visited file. Nothing is done if the current buffer is not
visiting a file, or is not modified.
- Function: unlock-buffer
This function unlocks the file being visited in the current buffer,
if the buffer is modified. If the buffer is not modified, then
the file should not be locked, so this function does nothing. It
also does nothing if the current buffer is not visiting a file.
- Function: ask-user-about-lock FILE OTHER-USER
This function is called when the user tries to modify FILE, but it
is locked by another user name OTHER-USER. The value it returns
tells Emacs what to do next:
* A value of `t' tells Emacs to grab the lock on the file. Then
this user may edit the file and OTHER-USER loses the lock.
* A value of `nil' tells Emacs to ignore the lock and let this
user edit the file anyway.
* This function may instead signal a `file-locked' error, in
which case the change to the buffer which the user was about
to make does not take place.
The error message for this error looks like this:
error--> File is locked: FILE OTHER-USER
where `file' is the name of the file and OTHER-USER is the
name of the user who has locked the file.
The default definition of this function asks the user to choose
what to do. If you wish, you can replace the `ask-user-about-lock'
function with your own version that decides in another way. The
code for its usual definition is in `userlock.el'.
File: elisp, Node: Information about Files, Next: Contents of Directories, Prev: File Locks, Up: Files
Information about Files
=======================
The functions described in this section are similar in as much as
they all operate on strings which are interpreted as file names. All
have names that begin with the word `file'. These functions all return
information about actual files or directories, so their arguments must
all exist as actual files or directories unless otherwise noted.
Most of the file-oriented functions take a single argument,
FILENAME, which must be a string. The file name is expanded using
`expand-file-name', so `~' is handled correctly, as are relative file
names (including `../'). Environment variable substitutions, such as
`$HOME', are not recognized by these functions. *Note File Name
Expansion::.
* Menu:
* Testing Accessibility:: Is a given file readable? Writable?
* Kinds of Files:: Is it a directory? A symbolic link?
* Truenames:: Eliminating symbolic links from a file name.
* File Attributes:: How large is it? Any other names? Etc.
File: elisp, Node: Testing Accessibility, Next: Kinds of Files, Up: Information about Files
Testing Accessibility
---------------------
These functions test for permission to access a file in specific
ways.
- Function: file-exists-p FILENAME
This function returns `t' if a file named FILENAME appears to
exist. This does not mean you can necessarily read the file, only
that you can find out its attributes. (On Unix, this is true if
the file exists and you have execute permission on the containing
directories, regardless of the protection of the file itself.)
If the file does not exist, or if fascist access control policies
prevent you from finding the attributes of the file, this function
returns `nil'.
- Function: file-readable-p FILENAME
This function returns `t' if a file named FILENAME exists and you
can read it. It returns `nil' otherwise.
(file-readable-p "files.texi")
=> t
(file-exists-p "/usr/spool/mqueue")
=> t
(file-readable-p "/usr/spool/mqueue")
=> nil
- Function: file-executable-p FILENAME
This function returns `t' if a file named FILENAME exists and you
can execute it. It returns `nil' otherwise. If the file is a
directory, execute permission means you can access files inside
the directory.
- Function: file-writable-p FILENAME
This function returns `t' if FILENAME can be written or created by
you. It is writable if the file exists and you can write it. It
is creatable if the file does not exist, but the specified
directory does exist and you can write in that directory.
`file-writable-p' returns `nil' otherwise.
In the third example below, `foo' is not writable because the
parent directory does not exist, even though the user could create
it.
(file-writable-p "~rms/foo")
=> t
(file-writable-p "/foo")
=> nil
(file-writable-p "~rms/no-such-dir/foo")
=> nil
- Function: file-accessible-directory-p DIRNAME
This function returns `t' if you have permission to open existing
files in directory DIRNAME; otherwise (and if there is no such
directory), it returns `nil'. The value of DIRNAME may be either
a directory name or the file name of a directory.
Example: after the following,
(file-accessible-directory-p "/foo")
=> nil
we can deduce that any attempt to read a file in `/foo/' will give
an error.
- Function: file-newer-than-file-p FILENAME1 FILENAME2
This functions returns `t' if the file FILENAME1 is newer than
file FILENAME2. If FILENAME1 does not exist, it returns `nil'.
If FILENAME2 does not exist, it returns `t'.
You can use `file-attributes' to get a file's last modification
time as a list of two numbers. *Note File Attributes::.
In the following example, assume that the file `aug-19' was
written on the 19th, and `aug-20' was written on the 20th. The
file `no-file' doesn't exist at all.
(file-newer-than-file-p "aug-19" "aug-20")
=> nil
(file-newer-than-file-p "aug-20" "aug-19")
=> t
(file-newer-than-file-p "aug-19" "no-file")
=> t
(file-newer-than-file-p "no-file" "aug-19")
=> nil
File: elisp, Node: Kinds of Files, Next: Truenames, Prev: Testing Accessibility, Up: Information about Files
Distinguishing Kinds of Files
-----------------------------
This section describes how to distinguish directories and symbolic
links from ordinary files.
- Function: file-symlink-p FILENAME
If FILENAME is a symbolic link, the `file-symlink-p' function
returns the file name to which it is linked. This may be the name
of a text file, a directory, or even another symbolic link, or of
no file at all.
If FILENAME is not a symbolic link (or there is no such file),
`file-symlink-p' returns `nil'.
(file-symlink-p "foo")
=> nil
(file-symlink-p "sym-link")
=> "foo"
(file-symlink-p "sym-link2")
=> "sym-link"
(file-symlink-p "/bin")
=> "/pub/bin"
- Function: file-directory-p FILENAME
This function returns `t' if FILENAME is the name of an existing
directory, `nil' otherwise.
(file-directory-p "~rms")
=> t
(file-directory-p "~rms/lewis/files.texi")
=> nil
(file-directory-p "~rms/lewis/no-such-file")
=> nil
(file-directory-p "$HOME")
=> nil
(file-directory-p
(substitute-in-file-name "$HOME"))
=> t
File: elisp, Node: Truenames, Next: File Attributes, Prev: Kinds of Files, Up: Information about Files
Truenames
---------
The "truename" of a file is the name that you get by following
symbolic links until none remain, then expanding to get rid of `.' and
`..' as components. Strictly speaking, a file need not have a unique
truename; the number of distinct truenames a file has is equal to the
number of hard links to the file. However, truenames are useful
because they eliminate symbolic links as a cause of name variation.
- Function: file-truename FILENAME
The function `file-truename' returns the true name of the file
FILENAME. This is the name that you get by following symbolic
links until none remain. The argument must be an absolute file
name.
*Note Buffer File Name::, for related information.